# Persistence3 - Complete Project Documentation

## Project Overview
**Persistence3** is a comprehensive vehicle persistence modification for Grand Theft Auto V that allows players to save, lock, and retrieve their customized vehicles across game sessions. This mod captures extensive vehicle data including modifications, colors, extras, and even radio stations and steering wheel positions.

**Version:** 1.1.2 (Bug Fixes)
**Status:** 100% Complete
**Date:** November 7, 2025
**Platform:** GTA V (Story Mode)
**Framework:** ScriptHookVDotNet v3.6.0+

---

## Table of Contents
1. [Features](#features)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Configuration](#configuration)
5. [Usage Guide](#usage-guide)
6. [Technical Details](#technical-details)
7. [File Structure](#file-structure)
8. [Saved Vehicle Data](#saved-vehicle-data)
9. [Troubleshooting](#troubleshooting)
10. [Development Notes](#development-notes)

---

## Features

### Core Features
- **Vehicle Locking/Unlocking System**
  - Lock vehicles with a single keypress (default: L key)
  - Controller support (default: Button 51)
  - Visual feedback with light flashing and horn
  - Key fob animation when locking/unlocking
  - Configurable lock cooldown to prevent spam

- **Comprehensive Vehicle Data Capture**
  - All vehicle modifications and customizations
  - Paint colors (primary, secondary, custom colors)
  - License plate and plate style
  - Window tint, tire smoke color
  - Neon lights configuration
  - Wheels, tires, and tire variations
  - Vehicle extras (spoilers, grilles, etc.)
  - Liveries and decals
  - Turbo, xenon headlights, bulletproof tires
  - Engine, brakes, suspension upgrades

- **Advanced Features** (Optional, configurable)
  - Drift tires persistence
  - Lowered suspension height
  - Crew emblems
  - Convertible roof state
  - **Fuel level persistence** (if fuel system enabled)
  - **Radio station persistence** - Saves current radio station
  - **Steering wheel angle persistence** - Saves wheel position

- **Intelligent Spawning System**
  - Distance-based spawning/despawning (configurable range)
  - Performance-optimized with cached distance calculations
  - Blips for persisted vehicles (optional)
  - Character-specific vehicle ownership (Franklin/Michael/Trevor)
  - Vehicle limit management (default: 150 vehicles)

- **Smart Lock/Unlock Detection**
  - Raycast-based vehicle targeting
  - Dynamic unlock distance based on vehicle size
  - "Last driven vehicle" tracking for quick locking after exit
  - 10-second window after exiting vehicle for easy locking
  - Visual prompts showing lock/unlock availability

- **Custom Vehicle Support**
  - Whitelist system for custom/addon vehicles
  - Prevents locking of mission vehicles (taxis, aircraft, etc. unless you drove them)
  - Validation to ensure only player-driven vehicles are saved

### Feedback Systems
- **Visual Feedback**
  - Vehicle light flashing on lock/unlock (configurable flash count)
  - Blips on map for locked vehicles
  - Color-coded blips by character (Michael=Blue, Franklin=Green, Trevor=Orange)
  - In-game notifications for all actions

- **Audio Feedback**
  - Vehicle horn on lock/unlock
  - Optional Persistence II style alarm chirps (1x lock, 2x unlock)
  - Key fob sound effects support
  - UI beeps for prompts

- **On-Screen Prompts**
  - Context-sensitive help text
  - Shows which vehicle you're targeting
  - Displays owner information
  - Shows lock/unlock action available

---

## Requirements

### Essential Requirements
1. **Grand Theft Auto V** - Latest version recommended (tested up to build 3442.0)
2. **Script Hook V** - Latest version by Alexander Blade
3. **ScriptHookVDotNet** - Version 3.6.0 or newer
4. **.NET Framework 4.8** - Pre-installed on Windows 10/11

### Optional Requirements
- **Audio files** for Persistence II style alarm chirps (chirp.wav)
  - Place in: `scripts/Persistence3/audio/chirp.wav`

---

## Installation

### Step 1: Install Prerequisites
1. Download and install **Script Hook V**
2. Download and install **ScriptHookVDotNet v3.6.0+**
3. Ensure .NET Framework 4.8 is installed

### Step 2: Install Persistence3
1. Create a `scripts` folder in your GTA V directory (if it doesn't exist)
2. Copy `Persistence3.dll` to the `scripts` folder
3. Copy `Persistence3.ini` to the `scripts` folder
4. The mod will automatically create:
   - `scripts/Persistence3/` folder for saved vehicles
   - `scripts/Persistence3/audio/` folder for sound files
   - `scripts/Persistence3.log` for logging

### Step 3: Configure (Optional)
1. Edit `Persistence3.ini` to customize settings
2. Add custom vehicle hashes to whitelist if using addon vehicles
3. Adjust key bindings, distances, and other preferences

---

## Configuration

### Configuration File: `Persistence3.ini`

#### [Keys] Section
```ini
LockKey=L                    # Keyboard key to lock/unlock vehicles
ControllerButton=51          # Controller button (DPad Right = 51)
```

**Common Controller Buttons:**
- 51 = DPad Right
- 50 = DPad Left
- 27 = DPad Up
- 26 = DPad Down

#### [Blips] Section
```ini
ShowBlips=true              # Show blips on map for locked vehicles
```

#### [Persistence] Section
```ini
MaxVehicles=150             # Maximum number of vehicles that can be saved
StreamDistance=200.0        # Distance (in meters) at which vehicles spawn/despawn
UnlockDistance=4.0          # Base distance for lock/unlock interaction
```

#### [Feedback] Section
```ini
FlashLightsOnLock=true             # Flash vehicle lights when locking/unlocking
LightFlashCount=2                  # Number of times lights flash (1-5)
HornLengthMs=200                   # Duration of horn beep in milliseconds
LockCooldownSeconds=3              # Cooldown between lock/unlock actions (1-5 seconds)
EnablePersistenceIIAlarms=false    # Use alarm chirp sounds instead of horn
```

#### [Debug] Section
```ini
LogLevel=Info              # Logging verbosity: Debug, Info, Warning, Error
```

**Log Levels:**
- `Debug` - Everything (very verbose)
- `Info` - General information, confirmations
- `Warning` - Issues that don't stop functionality
- `Error` - Critical errors only

#### [Features] Section
```ini
EnableAdditionalFeatures=false     # Enable drift tires, lowered suspension, crew emblems
EnableFuelSystem=false             # Enable fuel level persistence
```

**Additional Features Include:**
- Drift tire configuration
- Lowered suspension height
- Crew emblem persistence
- Vehicle corrosion (if available)

#### [CustomVehicles] Section
```ini
AllowCustomVehicles=false          # Allow custom/addon vehicles to be saved
VehicleList=                       # Comma-separated list of vehicle model names
```

**Example Custom Vehicle List:**
```ini
AllowCustomVehicles=true
VehicleList=lamborghiniaventador,nissangtr,toyotasupra,rx7
```

**How to Find Vehicle Model Names:**
- Use a trainer like Enhanced Native Trainer
- Check the addon vehicle's documentation
- Look in the vehicle's `vehicles.meta` file

---

## Usage Guide

### Basic Usage

#### Locking a Vehicle
1. **Drive a vehicle** (or be near one you just exited)
2. **Exit the vehicle**
3. **Aim at the vehicle** (looking at it)
4. **Press L** (or your configured key)
5. Vehicle locks, lights flash, horn beeps
6. Vehicle is now saved and persistent

#### Unlocking a Vehicle
1. **Approach a locked vehicle**
2. **Aim at the vehicle**
3. **Press L** (or your configured key)
4. Vehicle unlocks, lights flash, horn beeps
5. Vehicle data is deleted from persistence
6. Vehicle becomes temporary again

### Advanced Usage

#### Saving Multiple Vehicles
- You can save up to 150 vehicles (configurable)
- Each vehicle is saved individually with its own JSON file
- Vehicles are saved per character (Franklin, Michael, Trevor)
- You cannot unlock another character's vehicle

#### Vehicle Spawning
- Vehicles automatically spawn when you're within `StreamDistance` (default: 200m)
- Vehicles automatically despawn when you move away
- This saves performance and prevents game crashes
- Blips remain visible beyond spawn distance (if enabled)

#### Radio Station Persistence
- The mod automatically saves the current radio station when you lock a vehicle
- When the vehicle spawns back, it will be on the same station
- If radio was off, it stays off
- Bicycles don't have radios (saved as "OFF")

#### Steering Wheel Angle Persistence
- The mod saves the steering wheel position when you lock a vehicle
- Useful if you have a trainer that can lock steering angles
- The wheel position is restored when the vehicle spawns
- Note: Without a steering lock mod, wheels will naturally center

#### Working with Custom Vehicles
1. Set `AllowCustomVehicles=true` in the INI
2. Add vehicle model names to `VehicleList` (comma-separated, no spaces)
3. Model names should match the vehicle's spawn name
4. Example: `VehicleList=bmwm5,audir8,lambohuracan`

### Tips & Best Practices

#### Preventing Vehicle Loss
- **Always lock immediately after exiting** - You have a 10-second window
- **Check the prompt** - Make sure you see "Press [L] to save and lock"
- **Wait for confirmation** - Look for the notification and light flash
- **Don't drive away** - Stay within 15m until the vehicle is locked

#### Managing Vehicle Limit
- Default limit: 150 vehicles
- Check notifications - You'll be warned when limit is reached
- Unlock old vehicles you no longer need
- Consider increasing `MaxVehicles` if needed (may impact performance)

#### Performance Optimization
- Lower `StreamDistance` if experiencing lag (try 150m or 100m)
- Disable blips if you have many saved vehicles
- Reduce `MaxVehicles` if you don't need many cars
- Keep `LogLevel=Error` or `Warning` for best performance

#### Fuel System Usage
- Enable `EnableFuelSystem=true` to save fuel levels
- Requires a compatible fuel mod
- Without fuel mod, vehicles default to 65% fuel
- Fuel level is captured and restored with vehicle

---

## Technical Details

### Vehicle Data Storage

#### File Location
All vehicles are saved as individual JSON files in:
```
Grand Theft Auto V/scripts/Persistence3/
```

#### File Naming Convention
```
vehicle_PLATETEXT.json
```
Example: `vehicle_FRANKL1N.json`

#### JSON Structure
Each vehicle file contains approximately 50+ data points:

**Basic Information:**
- Model hash
- Position (X, Y, Z coordinates)
- Heading (rotation angle)
- License plate text and type
- Owner character hash

**Colors:**
- Primary color index (0-159)
- Secondary color index (0-159)
- Primary paint type (0-10: Normal, Metallic, Pearl, Matte, Metal, Chrome, etc.)
- Secondary paint type (0-10)
- Custom primary RGB (if custom)
- Custom secondary RGB (if custom)
- IsCustomPrimaryColor flag (authoritative for custom RGB)
- IsCustomSecondaryColor flag (authoritative for custom RGB)
- Pearlescent color
- Rim color
- Tire smoke color RGB
- Neon color RGB
- Trim color
- Dashboard color

**Modifications:**
- All 49 mod types (0-48)
- Window tint
- Wheel type
- Custom tires flag
- Back tire variation flag
- Livery index
- Extras (1-14)
- Neon lights (4 sides)

**Performance Upgrades:**
- Engine level (0-4)
- Brakes level (0-3)
- Suspension level (0-4)
- Turbo (yes/no)
- Bulletproof tires (yes/no)

**Lighting:**
- Xenon headlights (yes/no)
- Xenon color index

**Advanced (if enabled):**
- Drift tires
- Lowered suspension height
- Crew emblem
- Convertible roof state
- Fuel level
- Radio station
- Steering angle

**Example JSON Structure:**
```json
{
  "Model": "2598821281",
  "Position": {
    "X": -156.789,
    "Y": -1024.567,
    "Z": 29.123
  },
  "Heading": 45.67,
  "NumberPlate": "PERSIST",
  "PlateType": 0,
  "PrimaryColor": 0,
  "SecondaryColor": 0,
  "IsCustomPrimaryColor": true,
  "CustomPrimaryColorR": 255,
  "CustomPrimaryColorG": 0,
  "CustomPrimaryColorB": 0,
  "FuelLevel": 65.0,
  "RadioStation": "RADIO_LOS_SANTOS",
  "SteeringAngle": 15.5,
  "Mods": {
    "0": 2,
    "1": 1,
    ...
  }
}
```

### Distance Calculation System

The mod uses an optimized distance calculation system:

1. **Squared Distance Check** - Initial fast check using squared distances
2. **Distance Cache** - Distances calculated every 1.2 seconds
3. **Player Movement Check** - Recalculates if player moves >10m
4. **Spawn Priority** - Processes up to 5 vehicles per tick to prevent lag

### Lock Detection System

The mod uses multiple methods to find the target vehicle:

1. **Raycast** - Primary method, checks where camera is pointing (up to 15m)
2. **Last Driven Vehicle** - Fallback for recently exited vehicle (10-second window)
3. **Closest Persisted Vehicle** - Finds nearest locked vehicle within range

**Dynamic Unlock Distance:**
- Base distance: 4m (configurable)
- Adjusted by vehicle size (larger vehicles = longer range)
- Maximum distance cap: 15m

### Performance Optimizations

- **Asynchronous Save Queue** - Saves are queued and processed gradually
- **Asynchronous Delete Queue** - Deletions are queued and processed gradually
- **Distance Caching** - Avoids recalculating distances every frame
- **Spawn Throttling** - Max 5 spawns per tick
- **Lazy Loading** - Vehicles only load when player is nearby

---

## File Structure

```
Grand Theft Auto V/
├── scripts/
│   ├── Persistence3.dll          # Main mod file
│   ├── Persistence3.ini          # Configuration file
│   ├── Persistence3.log          # Log file (auto-generated)
│   └── Persistence3/             # Vehicle data folder (auto-generated)
│       ├── audio/                # Audio files folder (optional)
│       │   └── chirp.wav        # Alarm chirp sound (optional)
│       ├── vehicle_PLATE1.json  # Saved vehicle data
│       ├── vehicle_PLATE2.json
│       └── ...
```

---

## Saved Vehicle Data

### Complete List of Saved Properties

#### Basic Vehicle Properties
- `Model` - Vehicle model hash
- `Position` - X, Y, Z coordinates
- `Heading` - Rotation angle in degrees
- `NumberPlate` - License plate text (up to 8 characters)
- `PlateType` - License plate style (0-5)
- `OwnerCharacterHash` - Character who saved the vehicle
- `FileName` - JSON filename
- `LockStatus` - Current lock state

#### Color Properties
- `PrimaryColor` - Primary color index (0-159)
- `SecondaryColor` - Secondary color index (0-159)
- `PrimaryPaintType` - Paint finish type (0=Normal, 1=Metallic, 2=Pearl, 3=Matte, 4=Metal, 5=Chrome, 7=Special/Textured)
- `SecondaryPaintType` - Secondary paint finish type (0-10)
- `IsCustomPrimaryColor` - Boolean flag (true if custom RGB active)
- `CustomPrimaryColorR/G/B` - RGB values for custom primary (0-255)
- `IsCustomSecondaryColor` - Boolean flag (true if custom RGB active)
- `CustomSecondaryColorR/G/B` - RGB values for custom secondary (0-255)
- `PearlescentColor` - Pearlescent paint index
- `RimColor` - Wheel rim color index
- `TireSmokeColorR/G/B` - RGB values for tire smoke
- `NeonColorR/G/B` - RGB values for neon lights
- `TrimColor` - Interior trim color
- `DashboardColor` - Dashboard color

#### Modification Properties
- `Mods` - Dictionary of all 49 mod types (0-48)
- `WheelType` - Wheel category (0-11)
- `CustomTires` - Custom tire texture flag
- `BackTireVariation` - Rear wheel custom flag
- `WindowTint` - Window tint level (0-6)
- `Livery` - Livery/decal index
- `Extras` - Array of 14 extra toggles (bool)
- `NeonLights` - Array of 4 neon sides (bool)

#### Performance Properties
- `Engine` - Engine upgrade level (0-4, or -1)
- `Brakes` - Brake upgrade level (0-3, or -1)
- `Suspension` - Suspension level (0-4, or -1)
- `HasTurbo` - Turbo installed (bool)
- `BulletproofTyres` - Bulletproof tires (bool)

#### Lighting Properties
- `XenonHeadlights` - Xenon lights installed (bool)
- `XenonColor` - Xenon light color (0-12, or -1)

#### Advanced Properties (Optional)
- `DriftTires` - Drift tires enabled (bool)
- `LoweredSuspension` - Lowered suspension flag (bool)
- `SuspensionHeight` - Suspension height value (float)
- `HasCrewEmblem` - Crew emblem applied (bool)
- `ConvertibleRoofState` - Roof position (0=up, 2=down)
- `VehicleCorrosion` - Corrosion level (int)
- `DirtLevel` - Vehicle dirt amount (float, 0.0-15.0)

#### Special Features
- `FuelLevel` - Fuel amount (float, 0.0-100.0)
- `RadioStation` - Current radio station name (string)
- `SteeringAngle` - Wheel position in degrees (float, -720 to +720)

---

## Troubleshooting

### Common Issues

#### Vehicle Not Locking
**Problem:** Pressing L doesn't lock the vehicle

**Solutions:**
- Make sure you're within 4-10 meters of the vehicle
- Aim your camera at the vehicle
- Check if you see the prompt "Press [L] to save and lock"
- Verify the lock cooldown has passed (3 seconds default)
- Make sure it's not a restricted vehicle (taxi, aircraft you didn't drive)
- Check if you've reached the vehicle limit (150 default)

#### Vehicle Disappeared
**Problem:** Locked vehicle is missing

**Solutions:**
- Check if you're within spawn distance (200m default)
- Look for the blip on the map (if blips enabled)
- Check the log file for errors: `scripts/Persistence3.log`
- Verify the JSON file exists: `scripts/Persistence3/vehicle_PLATE.json`
- Make sure the game didn't crash while saving

#### Cannot Unlock Another Character's Vehicle
**Problem:** Can't unlock a vehicle locked by Michael/Franklin/Trevor

**This is intentional behavior:**
- Each character owns their own vehicles
- You can only unlock vehicles you locked
- Switch to the correct character to unlock
- Or manually delete the JSON file

#### Custom Vehicle Not Saving
**Problem:** Addon/custom vehicle won't lock

**Solutions:**
1. Enable custom vehicles: `AllowCustomVehicles=true`
2. Add vehicle to whitelist in `VehicleList`
3. Use the exact spawn name (check addon documentation)
4. Example: `VehicleList=bmwm5,nissangtr`
5. Restart the script after editing INI

#### Performance Issues / Lag
**Problem:** Game stutters or FPS drops

**Solutions:**
- Reduce `StreamDistance` (try 150 or 100)
- Lower `MaxVehicles` limit
- Disable `ShowBlips`
- Set `LogLevel=Error`
- Delete old unused vehicle files
- Check for other conflicting mods

#### Mod Not Loading
**Problem:** No notifications, nothing happens

**Solutions:**
- Verify Script Hook V is installed correctly
- Ensure ScriptHookVDotNet v3.6.0+ is installed
- Check for ASI loader (OpenIV > Tools > ASI Manager)
- Look for errors in `ScriptHookVDotNet.log`
- Make sure `Persistence3.dll` is in the `scripts` folder
- Try pressing Insert to reload scripts

#### Radio Station Not Saving
**Problem:** Radio resets to default when vehicle spawns

**Solutions:**
- Make sure you're using the latest version
- Check if radio was ON when you locked the vehicle
- Bicycles don't have radios (this is normal)
- Some vehicles don't support radios (this is normal)
- Check the JSON file to see if `RadioStation` is saved

#### Steering Wheel Not Persisting
**Problem:** Wheels return to center when vehicle spawns

**This is partially normal:**
- The steering angle IS saved to the JSON
- The angle IS restored when spawning
- BUT it won't STAY locked without an external mod
- You need a trainer/mod that locks steering to keep it
- The data is there for compatible mods to use

#### Vehicle Color Wrong After Reload (Fixed in v1.1.1)
**Problem:** Metallic red appears orange, colors look dull/wrong

**Fixed in version 1.1.1:**
- Enhanced Native Trainer compatibility improved
- Pure black custom colors now work (0,0,0 RGB)
- Textured paints with custom RGB work correctly
- Metallic/matte/chrome finishes properly restored

**If still experiencing issues:**
- Delete the vehicle JSON file and re-save
- Make sure you're using v1.1.1 or newer
- Check log file for paint-related warnings
- Set `LogLevel=Debug` to see detailed paint capture data

### Log File Analysis

The log file (`Persistence3.log`) contains valuable debugging information:

**Log Format:**
```
[YYYY-MM-DD HH:MM:SS]: [LEVEL] Message
```

**Example Logs:**
```
2025-10-23 14:30:15: [Info] Persistence3 Loaded
2025-10-23 14:30:15: [Info] Loaded 5 vehicles successfully
2025-10-23 14:31:22: [Info] Vehicle ABC123 saved and locked!
2025-10-23 14:32:45: [Warning] Failed to set mod kit for XYZ789
2025-10-23 14:33:10: [Error] Error in tick: NullReferenceException
```

**Common Error Messages:**

- `"Failed to load model"` - Vehicle model doesn't exist or isn't loaded
- `"Invalid vehicle provided"` - Trying to save null/deleted vehicle
- `"Failed to set mod kit"` - Some vehicles don't support mods
- `"Vehicle belongs to [Character]"` - Wrong character trying to unlock
- `"Maximum vehicle limit reached"` - Hit the MaxVehicles cap

---

## Development Notes

**Development documentation has been separated for privacy and distribution control.**

This includes:
- Code architecture
- Native functions used
- Design decisions
- Implementation details
- Technical specifications

---

## Credits & Acknowledgments

### Original Concept & Design
- **ImNotMentaL** - Original Persistence mod concept and design inspiration

### Development
- **Current Implementation:** Persistence3 RebelDragon1976
- **Framework:** ScriptHookVDotNet by crosire and contributors
- **Base Scripting:** Script Hook V by Alexander Blade

### Community
- **GTA V Modding Community** - For testing, feedback, and support
- **Persistence II Users** - For feature requests and inspiration

### Tools & Libraries
- **Newtonsoft.Json** - JSON serialization
- **ScriptHookVDotNet** - .NET scripting framework
- **Visual Studio** - Development environment

---

## Version History

### Version 1.1.1 (Hotfix) - November 5, 2025
**Status:** Critical Paint Fix

**What Was Fixed:**
- **Paint Capture & Restore System** - Complete overhaul of color handling
- **Pure Black Custom Color Fix** - Custom RGB (0,0,0) now saves correctly
- **Enhanced Native Trainer Compatibility** - Fixed garbage paint type data from vehicles without mod kit
- **Textured Paints with Custom RGB** - Brushed Gold, Utility, Worn textures with custom tints now work
- **Metallic/Matte/Chrome Finishes** - Paint types now properly detected and restored

**Technical Changes:**
- Changed IsCustom detection from RGB value check to proper native call (GET_IS_VEHICLE_*_COLOUR_CUSTOM)
- Removed validation clamping that was forcing invalid paint types to Normal (0)
- Added conditional paint type application - skips invalid values instead of applying garbage
- Improved debug logging for paint capture troubleshooting
- Fixed paint type field capture to store raw values without modification

**Why This Fix Was Needed:**
- Version 1.1.0 couldn't save pure black custom colors (detected as non-custom)
- Enhanced Native Trainer doesn't set vehicle mod kit, causing paint natives to return garbage
- Previous fix attempts broke regular metallic colors by clamping garbage to paint type 0
- Combined fix now handles both regular colors AND custom RGB correctly

**Impact:**
- All color types now save and restore correctly
- Works with all trainers (ENT, Simple Trainer, Menyoo, etc.)
- No more orange/wrong colors on metallic vehicles
- Textured special paints fully supported

---

### Version 1.1.0 (Final Release) - October 23, 2025
**Status:** 100% Complete

**Core Features:**
- Vehicle locking/unlocking system
- Complete vehicle data capture (50+ properties)
- Distance-based spawning/despawning
- Character-specific ownership
- Custom vehicle support
- Blip system with color coding
- Key fob animation
- Configurable light flashing and horn
- Persistence II style alarm chirps (optional)

**Advanced Features:**
- Fuel level persistence
- Radio station persistence ✨
- Steering wheel angle persistence ✨
- Drift tire support
- Lowered suspension support
- Crew emblem support
- Convertible roof state

**Performance:**
- Optimized distance calculations
- Queue-based save/delete system
- Spawn throttling (5 per tick max)
- Cached distance system

**Configuration:**
- Comprehensive INI file
- 20+ configurable options
- Custom vehicle whitelist
- Debug logging levels

**Known Limitations:**
- Steering angle requires external mod to stay locked (data IS saved)
- Some modded vehicles may not save all properties correctly
- Maximum recommended vehicles: 150 (configurable higher with performance impact)

**Fixed in v1.1.1:**
- Pure black custom colors (0,0,0) now save correctly
- Enhanced Native Trainer paint compatibility fixed
- Textured paints with custom RGB work properly
- All paint finishes restore correctly

---

## Future Considerations

This mod is **100% complete** for its intended purpose. However, potential future enhancements could include:

**Not Currently Planned:**
- Multiplayer/FiveM support (out of scope)
- Vehicle damage persistence (complex, performance impact)
- Passenger/driver NPC persistence (out of scope)
- Vehicle location tracking/GPS (out of scope)
- Remote locking (requires extensive UI work)

**These features are not needed for the mod's core functionality.**

---

## License & Distribution

### Usage Terms
- This mod is provided as-is for personal use
- You may modify for personal use
- You may share with others
- You may NOT claim as your own work
- You may NOT sell or monetize
- You MUST credit original author if sharing

### Disclaimer
- This mod is not affiliated with Rockstar Games
- Use at your own risk
- Always backup your save files
- No warranty or guarantee provided
- Author not responsible for game corruption or issues

---

## Support & Contact

### Getting Help
1. Read this documentation thoroughly
2. Check the Troubleshooting section
3. Review the log file (`Persistence3.log`)
4. Search for similar issues online

### Reporting Bugs
When reporting bugs, please include:
- Game version
- ScriptHookVDotNet version
- Persistence3.ini configuration
- Relevant log file entries
- Steps to reproduce the issue
- Screenshots/videos if applicable

---

## Final Notes

**Persistence3** represents a complete, production-ready vehicle persistence solution for GTA V. With support for over 50 vehicle properties, intelligent spawning, and advanced features like radio and steering wheel persistence, this mod provides comprehensive vehicle management without compromising performance.

The mod has been extensively tested and optimized for real-world use, with careful attention to edge cases, performance, and user experience. The configuration system allows for extensive customization while maintaining sane defaults for new users.

**Version 1.1.1** addresses critical paint capture and restore issues, ensuring full compatibility with all trainers and paint systems. All color types now work correctly, from standard metallic colors to textured special paints with custom RGB overlays.

**This project is considered 100% complete and feature-complete for its intended purpose.**

---

**Thank you for using Persistence3!**

*Enjoy your persistent vehicle collection in Los Santos.*

---

## Quick Reference Card

### Default Controls
- **Lock/Unlock:** L key (or DPad Right on controller)
- **Reload Scripts:** Insert key
- **Open Console:** F4 key

### Quick Config
```ini
# Essential settings
LockKey=L
MaxVehicles=150
StreamDistance=200.0
ShowBlips=true
FlashLightsOnLock=true
```

### File Locations
- **Mod:** `scripts/Persistence3.dll`
- **Config:** `scripts/Persistence3.ini`
- **Saves:** `scripts/Persistence3/vehicle_*.json`
- **Logs:** `scripts/Persistence3.log`

### Quick Troubleshooting
1. Vehicle won't lock? → Check distance & aim at vehicle
2. Vehicle disappeared? → Check spawn distance (200m default)
3. Mod not working? → Check ScriptHookVDotNet installed
4. Lag issues? → Reduce StreamDistance & MaxVehicles

---

*Documentation Version 1.1.1 - November 5, 2025*
*Persistence3 - Hotfix Release (Paint System Fix)*
